home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr10 / gsar106.zip / GSAR.MAN < prev    next >
Text File  |  1993-06-01  |  8KB  |  195 lines
  1.      Name
  2.           gsar - General Search And Replace utility
  3.  
  4.      Synopsis
  5.           gsar [options] [infile(s)] [outfile]
  6.  
  7.      Description
  8.           gsar ( General Search And Replace ) is a utility for searching
  9.           for and --- optionally --- replacing strings in both text and
  10.           binary files. The search and replace strings can contain all kinds
  11.           of characters ( 0-255 ), i.e. Ctrl characters and extended ASCII
  12.           as well.
  13.  
  14.           The algorithm used is a variation of the Boyer-Moore search
  15.           algorithm, modified to search binary files. As a result of
  16.           this, gsar is blindingly fast.
  17.  
  18.           Opposed to line oriented search programs (like grep), gsar will
  19.           find all matches on a line. Actually, gsar doesn't know anything
  20.           about lines at all, all files and strings are treated as binary.
  21.  
  22.           Gsar can search one or several files for a string and report
  23.           the occurrences. Gsar can read one file, search for a string,
  24.           replace it with some other string, and create a new file
  25.           containing the changes. Gsar can perform a search and replace
  26.           in multiple files, overwriting the originals. Finally, gsar
  27.           can work as a filter, reading from standard input and writing
  28.           to standard output.
  29.  
  30.      Options
  31.           All options can be concatenated into one single option
  32.           i.e the command: 'gsar  -i -b -l' is the same as 'gsar -ibl' 
  33.  
  34.           An option which takes an argument must be the last one in the 
  35.           concatenated option, since the rest of the option is taken as 
  36.           a possible argument. Generally arguments can either follow their
  37.           options directly or be limited by whitespace. The exceptions 
  38.           are listed below.
  39.  
  40.           Fields enclosed in [] are optional but mandatory when enclosed
  41.           in <>. Options are case sensitive i.e '-b' is not the same as
  42.           '-B'. 
  43.  
  44.           [infile(s)]
  45.               Name(s) of input file(s) (Wildcards allowed on most DOS
  46.               compilers). If the '-F' option is used input is taken from 
  47.               stdin.
  48.  
  49.           [outfile]
  50.               Name of output file that is to contain the replacements.
  51.               If the '-F' option is used, transformed output is sent to
  52.               stdout.
  53.  
  54.           -s<string>
  55.               String to search for in file. Ctrl characters can be entered
  56.               by using a ':' in the string followed by the ASCII value of
  57.               the character. The value is entered using a ':' followed by
  58.               three decimal digits or ':x' followed by two hex numbers.
  59.               To enter ':' use '::'
  60.  
  61.               example:
  62.  
  63.               To search for the string ':foo' ('o' is 111 decimal, 6F in hex.)
  64.               use: '-s::foo' or '-s::fo:111' or '-s::fo:x6F'",
  65.  
  66.           -r[string]
  67.               String which is to replace search string in file. Use '-r'
  68.               to delete the search string from the file i.e. replace with
  69.               nothing. Ctrl characters can be entered in the same way as
  70.               in the search string. If this option is left out, gsar only 
  71.               performs a search. 'string' must follow directly after 'r'.
  72.  
  73.           -i  Ignore case difference when comparing strings.
  74.               I.e. 'foobar' matches 'fooBAR'
  75.  
  76.           -B  Just display the search & replace buffers, for test purposes.
  77.  
  78.           -f  If the output file already exists this switch can be used to
  79.               force an overwrite of the existing output file.
  80.  
  81.           -o  Overwrite the input file(s) when performing a search
  82.               and replace. For each input file, gsar creates a tempfile
  83.               which contains the replacements, deletes the original file and
  84.               renames the tempfile to the original input file name. If no
  85.               matches were found in the file the input file stays the same
  86.               and the tempfile is removed.
  87.  
  88.               example:
  89.  
  90.               gsar -s__ZTC__ -r__TURBOC__ -o foo.c bar.c bat.c
  91.  
  92.               The resulting files: foo.c, bar.c & bat.c contain the changes.
  93.  
  94.           -c[n] 
  95.               Display the context around a match in a textual manner.
  96.               Undisplayable characters are displayed as a '.'. 'n' is 
  97.               optional number of bytes in context. 'n' must follow directly
  98.               after 'c'.
  99.  
  100.           -x[n] 
  101.               Display the context around a match as a hexadecimal dump.
  102.               Undisplayable characters are displayed as a '.'. 'n' is 
  103.               optional number of bytes in context. 'n' must follow directly
  104.               after 'x'.
  105.  
  106.           -b  Display the byte offset of the match in hex.
  107.  
  108.           -l  Only list filename and number of matches if any ( default ).
  109.  
  110.           -h  Suppress display of filename when displaying context or byte
  111.               offsets.
  112.  
  113.           -du Convert a DOS ASCII file to UNIX ( strips carriage return ).
  114.  
  115.           -ud Convert a UNIX ASCII file to DOS ( adds carriage return ).
  116.  
  117.           -F  'Filter' mode, gsar takes it's input from stdin and redirects
  118.               eventual output to stdout. All error messages are sent to 
  119.               stderr.
  120.  
  121.           -G  Display the GNU General Public Licence.
  122.  
  123.  
  124.      Examples
  125.           Search for two spaces at the end of a line ( DOS text ) and
  126.           replace with just a carriage return overwriting the original
  127.           files.
  128.  
  129.           gsar -s:x20:x20:x0d -r:x0d -o foobar.txt *.c
  130.  
  131.           Convert a UNIX text file to DOS format overwriting the original
  132.           file.
  133.  
  134.           gsar -ud -o unix.txt
  135.  
  136.           Search for the string 'WATCOM' and replace with '__ZTC__' using
  137.           gsar as a filter. Output is redirected to a new file.
  138.  
  139.           gsar -sWATCOM -r__ZTC__ -F < foo_w.c > foo_z.c
  140.  
  141.           Display textual context of the string 'error' in the file
  142.           gsar.exe disregarding case. With 40 bytes in the context.
  143.  
  144.           gsar -serror -i -c40 gsar.exe   
  145.  
  146.           Search for the string 'gnu' in the file 'fsf' and replace it
  147.           with 'wildebeest', creating a new output file 'africa'.
  148.  
  149.           gsar -sgnu -rwildebeest fsf africa
  150.  
  151.           ( if the file 'africa' exists, you have to use the '-f' option to
  152.             overwrite it. )
  153.  
  154.           Search for the string 'error' in the file 'command.com' and
  155.           display the byte offset of each match.
  156.  
  157.           gsar -serror -b command.com
  158.  
  159.  
  160.      Limitations
  161.           No wildcards or regular expressions allowed in search string.
  162.  
  163.           On MSDOS platforms stdin from a tty is not allowed because
  164.           stdin has been turned into binary. MSDOS will not catch the
  165.           Ctrl Z signifying EOF.
  166.  
  167.      Authors
  168.           Tormod Tjaberg ( coding, design (all bugs are his) )
  169.           Hans Peter Verne ( ideas, demands, testing, UNIX platforms )
  170.  
  171.           If you have any comments, bug reports or whatever, I (Tormod)
  172.           can be reached through email at hpv@kelvin.uio.no. This is not my
  173.           account so please address the message to me.
  174.  
  175.           Or if you a use a modem, mail me at Mike's BBS in Oslo Norway.
  176.  
  177.           Node 1: +47 22 41 65 88;  1200/2400/4800/9600+MNP (V.32)
  178.           Node 2: +47 22 41 04 03;  1200/2400/4800/9600+MNP (V.32)
  179.           Node 4: +47 22 33 73 20;  US Robotics Dual Standard HST/V.32
  180.   
  181.           8 data bits, 1 stop bit, no parity
  182.  
  183.           Sysop: Mike Robertson
  184.  
  185.      History
  186.           1.06 : GetArgs now uses GetOpt, context length can be specified on
  187.                  the command line. Setvbuf error is no longer fatal
  188.           1.05 : filter implemented, setvbuf used to speed up disk I/O,
  189.                  + bugfixes, see gsarbmg.c
  190.           1.04 : implemented signal handling.
  191.           1.03 : correct filename is now passed in OneSearchReplace
  192.           1.02 : BMG routines use compile time generated table instead of
  193.                  filling it in at run time
  194.           1.01 : First official version
  195.